\documentclass[article,oneside] {memoir}

\usepackage{graphicx}
\usepackage{booktabs}
\usepackage[colorlinks=true,linkcolor=red]{hyperref}
\usepackage{memhfixc}
\usepackage[left=2cm,top=2cm,right=2cm]{geometry}
\usepackage{setspace}
\usepackage{ulem}

\usepackage{url}

%% Define a new 'leo' style for the package that will use a smaller font.
\makeatletter
\def\url@leostyle{%
  \@ifundefined{selectfont}{\def\UrlFont{\sf}}{\def\UrlFont{\small\ttfamily}}}
\makeatother
%% Now actually use the newly defined style.
\urlstyle{leo}

\setlength{\parindent}{1pc}

\begin{document}
\thispagestyle{plain}

\begin{figure}[hbtp]
  \centering
  \includegraphics[width=0.4\textwidth]{./figures/xptracker_logo.png}
\end{figure}

\begin{center}
\huge{User Guide}
\end{center}

\setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}  

\chapter{Introduction}

\textsc{XPTracker} is an alternative agile tracking tool aimed at being as easy to use as possible while not imposing too many restrictions on software process.  As such, some of the concepts it introduces are not necessarily specific to any particular agile methodology, and the few tools it provides need to be customized to fit your organization's process.

For example: in some tools geared toward eXtreme Programming, you'll find the concept of "Releases" and "Iterations," and stored \textit{within} these time-boxed entities are "Stories," which contain "Tasks."  

Several of these metaphors are included in XPTracker, but their importance is de-emphasized or they are moved into separate ideas.  For example, a Release is composed of a list of items that must be done (as part of a Queue) and a list of items that have been done in a particular time slice (as part of a Timeline).  In this way, one can also express an Iteration or even a Sprint as a composition of a Queue and a Timeline.

What this means is that XPTracker is composed of fewer things that can be managed (Stories, Queues, and Timelines are the major players), but the composition of these items can be made to represent planning elements of several different methodologies, or even a custom process built by your organization.

This makes XPTracker both simpler and more powerful - simpler in that you can be up and running very quickly with minimal effort.  More powerful in that there are many more ideas that can be expressed with simple components to enable more complex management tasks for use with processes as simple as Scrum and as complex as RUP.
\newpage
\tableofcontents
\setcounter{tocdepth}{3}
\newpage

\chapter{Definitions}

\begin{description}
\item[Burndown Chart] A chart showing how much effort is left in a particular period of time.  Typically consisting of a single line that moves downward toward zero as stories are completed.  Several trends can be observed on a burndown chart -- if the line fails to move down, progress is stalled; if it moves up, estimates have increased or more stories introduced; if it moves down sharply, estimates have dropped or the team has gotten a jolt of energy suddenly.
\item[Customer] The stakeholder for the story.  Who wants this thing done?
\item[Estimate] Number of hours of effort the story should take to complete.  This number can be floating point.
\item[Open Queue] A queue where stories can be placed by anyone in the system, not just Planners.  Placement of stories into Open Queues happens only when the story is opened.
\item[Point] A unit of time related to the Size of a story.  Points can represent whatever your business needs them to represent.  These are generally more coarse-grained than hours, which are represented in the Estimate of the story.
\item[Priority] The absolute position of a story in the queue.  No story may share the same priority.
\item[Queue] A container for stories sorted either by priority or severity.  Some queues are "work queues," or queues that people pull stories from to work on, and others are "planning queues," useful for business prioritization.  Stories keep track of the queue they were last in, but this is separate from the state of being In Queue.
\item[Size] How "big" a story is.  The size of a story gets translated into points for planning purposes.  The translation of size to points can be configured in the Admin page.
\item[State] Where the story is (roughly) in the development process.  Stories can be in the following states: Dreaming, In Queue, In Process, Blocked, Rejected, Developed, Tested, and Released.
\item[Story] A description of a single unit of work to be done.  Generally equates to a Feature, or a part of a Feature.
\item[Task] A single technical item that contributes to the completion of a story.  Used by developers to break stories down into manageable pieces.
\item[Timeline] A set of rules that specifies how stories move in and out of Time Segments.  Each Timeline is associated with a collection of Time Segments.
\item[Time Segment] A single "slice" of time.  Stories move into and out of time segments according to the rules specified in the timeline that the segments are associated with.  For each time segment, there exists a report that shows the progress of all the stories slated for completion during that time, including a burndown chart.  To be "slated for completion" stories must meet a set of criteria specified on the Segment's timeline, which may include entering into a particular state (e.g. In Process), or into a queue (e.g. Current Iteration).  See Section \ref{sub:entryExitCriteria}.
\item[Tracker] A person that cares about the progress of this story.  When the story is changed, trackers receive notification (via the Dashboard and email) that the story changed and how.
\item[Wiki Page] A fast user-editable document that gets rendered as a nice web page.   For more on wiki pages, see Chapter \ref{chap:wiki}
\end{description}

\chapter{The Story}
\textsc{The Story} is the core of XPTracker.  It contains all the information necessary to figure out what must be done to complete a part of a feature.  Stories are placed within Queues, can have various items: files, customers, trackers, tasks, and blog entries.  Stories can also have effort associated with them, are used in reporting the progress of a Time Segment (see Section \ref{sec:timelines} : Timelines Page) and are the only things that can be searched for.  You can manipulate stories in various ways: by editing their core data, adding or removing various items, logging effort, and changing state.

Stories are one of a few items that can never be removed from the system.  Once entered, they remain forever.  The only way to make sure stories are clearly marked as unimportant is to move them to the "Rejected" state.  They will still be accessible by search, and recent activity on them will show up on users' dashboards.

\section{Story Links}

\begin{figure}[hbtp]
  \centering
  \includegraphics[width=0.4\textwidth]{./figures/storyLink.png}
  \caption{A link to a story.}
  \label{fig:storyLink}
\end{figure}

Whenever a link to a story is displayed, more information than just the story's summary is displayed.  On a single line, you can see almost every piece of status information for a story.  For example, in Figure \ref{fig:storyLink}, you can see a jagged blue line that represents how much effort has been logged as a percentage against the story over time.  After that is a small turtle image which represents one of the categories the story is in.  After that is a set of binoculars.

If you hover your mouse on the binoculars, another window pops up to show more story information such as that shown in Figure \ref{fig:storySummary}.

\begin{figure}[hbtp]
  \centering
  \includegraphics[width=0.75\textwidth]{./figures/storySummary.png}
  \caption{Some story details.}
  \label{fig:storySummary}
\end{figure}  

\section{Adding a Story}
The simplest thing that can be done in XPTracker is creating a new story.  Simply press "Add a Story" at the top of the page and fill out the information on the form.  There are only 6 fields to fill out: Summary, Severity, Size, Due Date, Estimate, and Description.  The summary is the only field that is required.  All others will be set to sensible defaults.  The description uses Wiki markup.  To see what the description looks like, press the "Preview Description" link.  For help with wiki markup, see Chapter \ref{chap:wiki}: Wiki Markup.

When a story is opened, it can be placed in one of two states: Dreaming, or In Queue.  When a story is in "Dreaming" state, it hasn't been planned yet.  This doesn't stop users from being able to start working on a story (in the case that your organization doesn't use queues at all), but it will circumvent any timeline tracking based on entry into a queue (see Section \ref{sec:timelines}: Timelines Page for more information)

Putting a story directly to In Queue can only be done if your system has Open Queues.  If there are any Open Queues, a dropdown will be presented on the story which defaults to "None."  If you select "None," the story will be placed into the Dreaming state.  However, if you select a queue, it will be placed into the queue and into the In Queue state.

\section{Editing a Story}
Editing a story is as simple as clicking the "Edit" link on the story display page.  From there you can change any of the fields that were originally entered.

\section{Blog}
The blog is where conversation happens about a story.  Blog entries are generated when entered directly by a user, or when a story is edited or its state is changed.

To add a blog entry, click the Update Story link and enter your blog entry.  Press "Add Blog Entry" and your comment will be added and emailed to the trackers on the story.  Responding to an email generated by a blog entry will send an email directly to the person that wrote the entry, but will not be entered on the story.

Blog entries use wiki markup.  To see what the rendered blog entry looks like, press the "Preview" link.  For help with wiki markup, see Chapter \ref{chap:wiki}: Wiki.

\section{Time Tracking}
\label{sec:timeTracking}
When the "Effort" link on a story, or one of its tasks, is clicked, a window pops up allowing you to log effort against the story.  You'll notice that when you first bring up the effort window, a series of green buttons marked "Start" appear on the right-hand side, with a large empty white box on the left.  This box is where existing time entries are displayed.  Above the white box is a comment field.  Any text filled into this field when the "Start" or "Stop" button is pressed will be attached to any generated time entries.

This first view is called the \textit{Time Clock} view.  When you begin to work on a story, you can simply press the "Start" button next to the name of each person that is working on the story, and the system will track time for you.  When you've finished, simply return to the Effort page and press "Stop."  Entries will be generated for each person whose clock has just stopped.

\textbf{Note}: The only names that appear with "Start" buttons next to them are the names of people tracking the story and people who have had manual effort entries logged in their name.

If you forget to log time for a story while you're working on it, you can switch to the \textit{Manual Entry} view.  This allows you to enter single line items of time for each person that worked on the story.  Simply press the "Add" button and fill in the start and stop times during which the effort was completed, and select the person's name.  After you've finished completing all the line items you wish to add, press "Save."

Optionally, you may also add comments for each time entry you create, or modify comments for existing time entries.

To remove an entry, simply wipe out the start time from the text field and it will be deleted.

\subsection{Task Effort}
When the "Effort" link is pressed next to a task, the effort logged is against the story, not the task.  The link exists next to the task so that the summary of the task can be automatically entered into the time entry page.  No direct link is made between effort entries and the tasks associated with them, so you can feel free to delete a task without losing any of the time you logged.  As a consequence, changing the summary of a task will not affect any of the effort entries logged against the story with the task's prior summary used as a description.

\section{Modifying Story Data}
Various parts of the story can be modified directly on the display page.  On the right-hand side, below the Status section, are all of the items that can be modified.

\subsection{Adding a File Attachment}
Simply click the "Add" link in the Attachments box and, in the box that pops up, enter a description and choose the file you wish to upload.  When you press "Attach" the file will be uploaded and the Attachments list will be immediately refreshed.

\subsection{Tasks}
Click "Add" in the Tasks box, enter the required information, and press "Create."  Only the Summary field is required for this step.  You can edit existing tasks by pressing the "Edit" link next to the story, or delete them by pressing "Delete."

Reorder a task by dragging the row that the task is done until it is in the place you want it to be.  When you let go, the task will have been reordered.

Task completion can be signified by clicking the checkbox to the left of the task.  When the box is checked, the task will be immediately marked as complete.

The Effort link next to each task is a convenience method for automatically entering a comment (the task summary) into the Effort page.  See Section \ref{sec:timeTracking}: Time Tracking for more information.

\subsection{Categories}
\label{sec:categories}
Categories change the display of the story - if a Category has an image associated with it (this can be modified by Administrators), then whenever a link to the story is displayed, that image is also displayed to show that the story is in that category.  You can also search for stories in a particular category.  See Chapter \ref{chap:searching}: Searching.

Add a category by clicking the dropdown at the bottom of the Categories box and selecting the category to add.  After you have clicked the category, it will be immediately added to the story.  

\subsection{Trackers}
Trackers can be added just like Categories (See Section \ref{sec:categories}) can.  However, once a tracker other than yourself is added, only they can remove themselves from the list.  To remove yourself from a story as tracker, simply click "Stop Tracking" in the Trackers box.  If the "Stop Tracking" link doesn't appear, that means you own the story.  You must always track all stories that you own.

\subsection{Customers}
Customers are maintained just like Categories (See Section \ref{sec:categories}).  The only difference is that, if you're a Planner, you can add a new customer from the same dropdown.  Simply click "New..." at the bottom of the Customers dropdown and you will be prompted for the new customer name.  After you've entered the name, the customer will be created and added to the story immediately.

\chapter{Searching}
\label{chap:searching}
\textsc{Using} the search tool is the easiest way to find something.  It is also the best way of expressing a set of stories in the system.  A simple example, to get us started:

\begin{quotation}
\texttt{state:(inprocess OR inqueue) AND queue:"Current Release"}
\end{quotation}

This means I want every story that is either being worked on (inprocess) or slated to be worked on (inqueue) that is in the "Current Release" queue, or came out of the "Current Release" queue.  Since a story keeps track of the last queue it was in, this information is available even if the story has been fully developed.

Other methods for searching are more intuitive:

\begin{quotation}
\texttt{flower}
\end{quotation}

This finds every story that has "flower" anywhere in its content.  This searches all of the story's fields at once and may return a very large list.  If you wish to drop this list in size, consider narrowing which field you wish to search in:

\begin{quotation}
\texttt{summary:flower}
\end{quotation}

This finds stories that only have "flower" in their summary.

For the most complete list of fields you can search, and ways you can combine queries, click the "[?]" link in XPTracker next to the Story Search button.  This will give you in-application help for executing queries.

\section{Saving Searches}
\label{sec:savingSearches}
Saved searches are very helpful.  When you type in the query you wish to save, simply click the "Save" link and then press "Story Search."  This will execute the query and also save it in the system with the name you typed in.  If that name already exists, it will be overwritten.

You can load a saved search by simply clicking the "Load..." dropdown and selecting the search you want to use.  You can also use saved searches in the Planning page (Section \ref{sec:queuesArent}) as well as on your Dashboard (Chapter \ref{chap:dashboard}).

Saved searches can be deleted on the Profile page (Section \ref{sec:profile}).

\chapter{Customizing Your View: The Dashboard and User Profile}
\label{chap:dashboard}
\textsc{One} of the most important features of XPTracker is the dashboard.  From here you can see at a glance how everything you care about is doing.  Everything you're working on, timeline (Section \ref{sec:timelines}) charts, queues, and saved searches (Chapter \ref{chap:searching}) can all be added to your dashboard.  Also, all the most recent activity on every story you're tracking is displayed for quick review.

\section{Your Profile}
\label{sec:profile}
To add any of these items to your Dashboard, click the Profile link.  This section allows you to modify information about your account (including the email address used to send you updates) as well as add subscriptions to your Dashboard.  To put a queue on your dashboard, simply check the box next to the queue to add.  The same applies to timelines (Section \ref{sec:timelines}) and saved searches (Section \ref{sec:savingSearches}).  The top 6 items in each queue will be displayed, all the results of each search, and the burn chart (Section \ref{sec:burnChart}) of the current segment of each timeline.

From the profile you can also delete any saved searches that you might wish to be rid of by clicking the "Delete" link next to the search.

Changing your password is also simple.  Click the "Change Password" link, enter your new password twice, and press "Save."

\chapter{Wiki}
\label{chap:wiki}
\textsc{XPTracker} comes with a full-featured wiki built-in.  With this wiki, you can create documentation  quickly by simply typing WikiWords into your story descriptions, task descriptions, blog entries, or even other wiki pages.  All wiki pages are located under the Wiki tab.  When you type a wiki page, you use Wiki Markup.  In XPTracker, this markup is limited (see below), but can be augmented by typing in your own HTML.

To change a wiki page, simply click the Edit link at the top of the page.  If you'd like to see what your changes will look like on the site, click the Preview link.  Or, just press Save to save your changes.

\section{Wiki Markup}
Several parts of the system use a customized Wiki markup language based on Markdown.  All Markdown syntax is supported, plus a few extra widgets, as specified below.  For an introduction to Markdown syntax, visit \url{http://daringfireball.net/projects/markdown/}.

\section{Links}

\begin{verbatim}
WikiWord

SomeOtherWord
\end{verbatim}
\begin{quotation}
  \protect\underline{WikiWord}
  
  \protect\underline{SomeOtherWord}
\end{quotation}

\textit{These links will take you to the wiki section of the website.  If you use WikiWords in a story description, you will be able to go back to the story by following the breadcrumb trail at the top of the wiki display screen.}

\begin{verbatim}
item:1234

item:4567
\end{verbatim}
\begin{quotation}
  \protect\underline{Story 1234: A quick summary of the story}
  
  \protect\underline{User 4567: Bob Smith}
\end{quotation}

\begin{verbatim}
  jira:BUG-123
\end{verbatim}

\begin{quotation}
  \protect\underline{jira: BUG-123}
\end{quotation}

\textit{Note: This structure is used only if the administrator has set up an external link for "jira".  See Section \ref{sec:extLink}}


\chapter{Planning}

\textsc{Planning} with XPTracker is performed in two sections: the Planning page and the Timelines page.  The planning page is used to move stories between queues (Section \ref{sec:queues}) prioritize stories within queues (assuming the queue is a Priority Queue), and modify severity, size, or estimate en masse.  The planning page is \textbf{not} used for specifying which stories are slated for which release of the software.  In fact, if one were to create multiple queues, one for each release, one would eventually end up with dozens of empty useless queues, since stories are always moved out of the queue when they are worked on.  If you want to specify which items made it into a particular release, use Timelines (Section \ref{sec:timelines}).

\section{Queues}
\label{sec:queues}
Queues are containers of stories.  The presence of a story in a queue marks its inclusion in a planned block of work, either present or future.  Once a story enters a queue, it forgets whatever queue it used to be in (or whatever state) and becomes wholly owned by the new queue. 

Any Timeline (Section \ref{sec:timelines}) whose entry criteria contain the queue will automatically include the story in any time segments for which the story was in the queue.  In this way, if a story simply stays in a queue across multiple segments, it will automatically roll through them until it is marked complete.  No action is required to "continue" a story from one iteration to the next, nor does the system have to do any work to make sure stories do so: Timelines specify "when" a story should have been done, and queues specify "where" a story is.

Queues can provide a unique priority for each story contained within.  When the priority of a story is changed, any story in its new slot will be pushed down.  Because of this restriction, planners are forced to make decisions about the order in which things are completed.  These queues are called Priority Queues.

Queues can also be sorted in order of severity.  A Severity Queue should never be used as a work queue, but only as a high-level planning queue.  Severity Queues are convenient for segregating work into separate staging areas to be pulled into work queues at a later time.

By default, a queue can only receive items during planning (Section \ref{sec:moving}).  However, you can mark the queue as "Open" by clicking the "Open" button next to the queue on the Queues page.

Once a story has been placed in a queue, the fact that it was in the queue is permanently burned into its history (it was a member of a time segment including that queue at one point in time, even if it was subsequently removed to another).  This means that, once a queue has contained stories, it can never be removed.  Nor can a queue ever be renamed, since its name is also a vital part of the story's history.  In order to be able to remove a queue that has participated in a story's history, one would effectively be rewriting history, a power granted only to database administrators to be used under dire circumstances and with full understanding of the consequences.

\section{Planning Page}
The Planning Page can be used to perform 3 kinds of tasks: Moving, re-prioritizing, and modifying stories in a queue.  Each of these activities can be performed separately or all at once.

Hello bob.

\subsection{Moving Stories}
\label{sec:moving}
In order to move a story from one place to another, simply ensure that the destination queue is selected in the Destination dropdown and then check the box next to each story you wish to move into that destination.  Note that as you check boxes, the number of points and hours changes: the points and hours for the checked story are subtracted from the source and added to the destination.  Stories will not be moved until you press "Save Changes."

\subsection{Prioritizing Stories}
The priority of a story is displayed in a text box to the left of the story description.  When the queue is first loaded (by changing the Source) in the dropdown at the top of the page), the numbers are sequential.  However, these numbers can be changed.  Whenever a priority is changed from what it was originally, the story will be placed into the position you entered, and whatever was in that position before will be moved down.  If multiple changes are made, the stories where priorities are changed are guaranteed to be in the positions you specified.  All other stories will be pushed down appropriately.  Priorities will not actually change until you press "Save Changes."

\subsection{Modifying Stories}
The Severity, Size, and Estimate of a story can be changed on the planning page.  Simply click the arrows to modify the Severity or Size, or change the estimate, and when you press "Save Changes," each of the stories will be modified accordingly.

\subsection{Some Queues Aren't}
\label{sec:queuesArent}
The Source dropdown doesn't just contain queues.  It also contains several conveniences to allow you to pull stories from several areas into one queue.  

The "Dreaming" queue is a list of all stories in the Dreaming State.  This item is always at the top of the Source dropdown.

After "Dreaming" is a list of all saved searches.  When picking a saved search, that search is executed and the results are listed in the Planning page in order of relevance.  See Chapter \ref{chap:searching} for information on searching.  After the saved searches are the queues in the system.

\subsection{Important Note}
When you press "Save Changes" all changes are applied at once.  Stories will be moved, re-prioritized, and modified in one fell swoop.  All of the changes for each story will be enumerated in a single blog entry which will then be sent to each of the trackers on the story.

\section{Timelines Page}
\label{sec:timelines}
Where the Planning Page is used for manipulating what the plan is now, the Timelines page is used for tracking trends of activity over a particular time period.  If you're an administrator, you can use the Timelines page to create new time segments, manipulate existing ones, and change criteria for entry and exit into and out of a segment.  If you're not, you can only view existing Time Segments.

\subsection{Adding a Timeline}
\label{sub:addTimeline}
To create a new Timeline, simply scroll to the bottom of the page and fill in the form labeled "Add a Timeline."  When you press "Add" the timeline will be created.  \textbf{Note}: the Timeline is useless unless you have specified some Entry and Exit criteria.

\subsection{Editing a Timeline}
To edit an existing Timeline, click the "Edit" button next to the timeline.  The form at the bottom of the page will change from "Add a Timeline" to "Edit a Timeline."  Make changes to the timeline and press "Save."  If you change your mind and don't want to edit that timeline and instead want to add a new one, press the "Add" button.

\subsection{Entry and Exit Criteria}
\label{sub:entryExitCriteria}
A story moves through Time Segments by changing state or being placed in or removed from a queue.  There are three ways a story can move through a segment: Entry, Exit, and Removal. 

A story enters the segment if it has met one of the Entry Criteria and not any of the Exit Criteria during the segment's lifetime (bounded by its start and stop dates).  This story will then be listed in the "Not Completed" section of the Time Segment report and cause the lines on the chart to go up.

When a story exits the time segment, it must have entered the segment during the segment's lifetime and meet one of the Exit Criteria.  This would place the story in the "Completed" section on the report and cause the line on the chart to drop.  Meeting an exit criterion is the only way a story burns down.

Removal from the time segment occurs when the story enters the segment at one point in time, and then at a later point no longer meets the Entry Criteria but also doesn't meet any Exit Criteria.  This usually occurs because the story is removed from scope (by being moved from one queue to another or Dreaming) or rejected outright.  Removal of a story will cause the story to be listed in the "Removed" section of the report.  Removal also affects the line on the chart in the same way as "Exiting," but also registers a "Feature Reduction" event.  See the Section \ref{sec:burnChart}: The Burn Chart for further information.

To add an Entry or Exit criterion, simply pick which kind of criterion to add (Queue or State), and then select the exact queue or state.  After you've made your selections, press "Add."  To remove the criterion, press the "x" next to the criterion.

\subsection{Adding and Editing Time Segments}
Time Segments can be added and edited just like Timelines (Subsection \ref{sub:addTimeline}).  However, instead of a burn granularity and measurement you'll need to enter a start and stop date. 

\subsection{The Burn Chart}
\label{sec:burnChart}

\begin{figure}[hbtp]
  \centering
  \includegraphics[width=0.9\textwidth]{./figures/burn1.png}
  \caption{An example burn chart where the team got more work done than it had initially planned.  The feature set was increased, but the burn went to zero.}
  \label{fig:burn1}
\end{figure}

As stories move through a Time Segment, the burn chart changes.  When a story Enters the segment, the line goes up based on the size of the story, if the Timeline is measured in Points, or the estimate of the story if the Timeline is measured in Hours or Hours Remaining.  If the story enters the segment in the middle (not on the first day) of the segment, then the chart registers "Feature Creep" by rendering a solid red bar equal to the size or estimate of the story based on the same rules.  This bar is then stacked on a shaded red bar which measures previous Feature Creep that has already occurred.

When a story is removed from a Time Segment in the middle (not on the first day), a blue bar is rendered in the same way the "Feature Creep" bar is rendered.  The only other difference besides the color is that the bar moves in the opposite direction.

The solid line of the burn chart measures how much effort is remaining in the time segment.  This effort can be measured in Points or Hours, and goes down only if: 
\begin{enumerate}
\item A story Exits or is Removed from the Time Segment, 
\item A story's estimate is dropped, or
\item A story has effort registered against it and the Timeline is measured in Hours Remaining.
\end{enumerate}

Similarly, the solid line goes up only if:
\begin{enumerate}
\item A story Enters the Time Segment, or
\item A story's estimate is increased.
\end{enumerate}

The dashed line on the chart follows many of the same rules as the solid line.  However, the dashed line only shows the \textbf{original estimates} of the unfinished stories when they first entered the timeline.  Any changes to a story's estimate will not cause the dashed line to change.  Nor will changes to effort logged against it.  The only way the dashed line goes up or down is if a story enters, exits, or is removed from the segment.  See Figure \ref{fig:burn1} for an example.

\chapter{Administration}
\textsc{Administration} and maintenance of XPTracker is performed via the Admin Tools menu.  This menu will only appear if your account is in the Planner or Admin role, and its submenus will be larger or smaller depending on which of those roles you are in.

\section{First Run}
\label{sec:firstRun}
When XPTracker firsts starts up, it begins life by automatically constructing its database schema.  After that, it runs a series of automatic data updates, one of which creates the first user account.  This account's username is "admin" and its password is "admin".  You should change this password immediately! See Section \ref{sec:profile} for more information.

\section{Scheduled Tasks}
The Scheduled Tasks section is located under Admin Tools, System.

The system can execute regular tasks according to a schedule.  Some tasks are included when you first start up the system: Load Timeline Charts, Optimize Database, and Optimize Search Index.  To edit a task, click the link to the task.  If the task is provided by the system, you may only change the schedule.  Otherwise, you may change the task's name and the script it executes.

The schedule is specified in a modified cron format.  This format is:
\begin{quotation}
  \texttt{second  minute  hour  day\_of\_month  month  day\_of\_week}
\end{quotation}

If you use a "*" in any of these positions, the system will execute the task on every item in that category.  If you use "*/15" then the system will execute every 15 units.  If you use "day of month," then the "day of week" must have a "?" in its position, and vice versa (they are mutually exclusive).

Examples:
\begin{quotation}
  \texttt{0 */15 * ? * *}
  \par Every 15 minutes.
\end{quotation}

\begin{quotation}
  \texttt{0 0 0 ? * SAT}
  \par Every Saturday at Midnight.
\end{quotation}

\begin{quotation}
  \texttt{0 0 22 ? * *}
  \par Every day at 10pm
\end{quotation}

You may also Disable a task, which causes it never to run, or delete a task if it isn't a system task, by clicking the Delete link next to the task.

To learn more about how to write scripts in XPTracker, see Chapter \ref{chap:adminApi}: Administration API.

\section{Import/Export}
The Import/Export section is located under Admin Tools, System.

You can import Users, Stories, or Customers into XPTracker via the Import/Export section.  Simply select Browse... and select the file you wish to import.  After pressing the Import button your data will be loaded into the system immediately.  All import files (except the XPlanner import) must be in CSV format (generated using Excel or otherwise).  To get a sample of what these files should look like, click the Export link for any type, and the existing data in the system will be exported in the same format.

\section{Story Points}
The Story Points section is located under Admin Tools, System.

To change how many points each size increment is mapped to, change the numbers in the Story Points section.  Then press Save.

\section{External Link Formats}
\label{sec:extLink}
The External Link Formats section is located under Admin Tools, System.

External links allow users to create easy links to external systems by using wiki shortcuts in story descriptions or blog entries.  These shortcuts are in the form \textit{name:id}.  The name of the link format is specified when you create the mapping by pressing "Add" in the External Link Formats section.  After you enter the name, a new row will appear allowing you to specify the URL that the external link requires.  This URL may include \texttt{\{0\}}, which is the insertion point for the ID that the user specified.

For example, given an external link format named "app" with the URL \texttt{http://externalSystem/displayTicket?id=\{0\}}, a user may type:

\begin{quotation}
\texttt{app:42}
\end{quotation}

Which would cause the system to render a link to:

\begin{quotation}
\texttt{http://externalSystem/displayTicket?id=42}
\end{quotation}

\section{Users}
Users can be managed under Admin Tools, Users.

Adding users is simple.  Just click "Add," enter the new username, and press OK.  The user will be added and a password assigned.  Give that password to the new user and they can then log on and change their password on the Profile page (Section \ref{sec:profile}).  To grant or revoke roles to/from the user, simply click the button to the right of the user corresponding to the privilege and it will be immediately added or removed.  You can also disable the user, which causes them to be unable to log on, and also removes their name from any dropdowns that include users, such as trackers.

\section{Categories}
Categories can be managed under Admin Tools, Categories.

Adding and removing categories is as easy as clicking "Add" or "Delete."  You can also change the icon of the category by clicking the existing icon or the "(Icon)" link if there isn't one.  A box will open up allowing you to upload the new file by clicking "Browse..." and selecting the new file and then pressing "Update."

By default, all categories are of the same type: none.  However, if you give a category a type, it will be placed into a group of that name when it is displayed in the Add or Display Story pages.  Simply enter the type into the text field and press "Save," and the category will be placed in that type.

\section{Customers}
Customers can be managed under Admin Tools, Customers.

To add a customer, click "Add," enter the customer name, and press OK.  To delete a customer, press the Delete button next to the customer name.

\section{Email Configuration}
The system's Email Configuration can be managed under Admin Tools, Email Configuration.

To enable email, click the checkbox next to "Enabled."  In order for this to work, however, you must enter a valid SMTP host.  If this host is invalid, email sending will fail and users will be notified with error messages.  If authentication is required, enter the Username and Password in the appropriate fields.

\chapter{Administration API}
\label{chap:adminApi}

\chapter{FAQ}
\label{chap:faq}
\textbf{Whenever I create a story, it always goes into Dreaming.  How can I make stories go straight into a queue?}

If you mark a queue as \textit{Open}, then it will be available on the Add a Story page in the Queue dropdown.  See Section \ref{sec:queues} for more information.

\begin{center}
  \begin{verbatim}
  
  
  
  \end{verbatim}
\small{Document generated on: \today}
\end{center}

\end{document}